Refactor CopilotClient initialization and enhance documentation by brettcannon · Pull Request #519 · github/copilot-sdk

brettcannon · 2026-02-19T22:54:35Z

Refactor the CopilotClient constructor to use keyword arguments for improved IDE support and type checking. Update the constructor to accept path-like objects and document changes in the README, including valid log levels and new parameters. Add overload signatures for better type checking and clarify nullable types in the documentation.

… arguments Replace the options dict parameter with explicit keyword-only arguments for better IDE support, type checking, and discoverability. Update docstrings, examples, and all call sites accordingly.

Update cli_path and cwd parameters to accept Union[str, os.PathLike[str], None]. Values are normalized to str via os.fspath() before storage.

- Fix stale event['type'] to event.type.value in API Reference example - Update cli_path/cwd types from (str) to (str | PathLike) - Fix cli_path default description: remove stale COPILOT_CLI_PATH reference - Document log_level valid values (none, error, warning, info, debug, all) - Export LogLevel type from copilot/__init__.py

@overload

…ecking Add two @overload declarations to distinguish between cli_url mode (connecting to an external server) and cli_path mode (launching a local CLI process). This provides clearer IDE autocompletion and type-checker support for mutually exclusive parameter groups. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add env parameter to CopilotClient Options and update type annotations to show | None for all parameters that accept None. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

# Conflicts: # python/copilot/client.py

Copilot

Pull request overview

Refactors the Python SDK’s CopilotClient initialization to use keyword-only parameters (with overloads for better type checking), adds PathLike support for cli_path/cwd, and updates tests and Python README examples to match the new API.

Changes:

Reworked CopilotClient.__init__ to accept keyword arguments (and added typing.overload signatures) plus os.fspath() normalization for path-like inputs.
Updated unit + E2E tests to call CopilotClient(...) with keyword args; added unit tests covering PathLike inputs.
Updated python/README.md to document new parameters/types (including valid log levels and env) and adjusted example usage.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
python/test_client.py	Updates constructor usage and adds PathLike argument tests.
python/e2e/testharness/context.py	Updates E2E harness to instantiate `CopilotClient` via keyword args.
python/e2e/test_session.py	Updates session resume E2E to use keyword args for `CopilotClient`.
python/e2e/test_client.py	Updates E2E client tests to use keyword args.
python/copilot/client.py	Implements keyword-only constructor, adds overloads, supports PathLike inputs, updates docstrings/examples.
python/copilot/init.py	Exports `LogLevel` in the public Python package surface.
python/README.md	Updates Python README examples and documents updated `CopilotClient` parameters and log levels.

Comments suppressed due to low confidence (2)

python/copilot/client.py:246

env is only copied into self.options when it is truthy (if env:). This means callers cannot intentionally pass an empty dict to fully clear the subprocess environment, and it also makes the README semantics (“replaces the inherited process environment”) unreliable. Check env is not None instead of truthiness when deciding whether to persist the provided env.

        if cli_url:
            self.options["cli_url"] = cli_url
        if env:
            self.options["env"] = env

python/copilot/client.py:148

This change removes the previous CopilotClient(options: dict) calling pattern entirely (constructor is now keyword-only). Since this is the public entry point for the Python SDK, consider keeping backwards compatibility by accepting the old options dict (and mapping it to keyword args) with a deprecation warning, or explicitly documenting the breaking change and bumping the package version accordingly.

    def __init__(
        self,
        *,
        cli_path: Union[str, os.PathLike[str], None] = None,
        cli_url: Optional[str] = None,
        cwd: Union[str, os.PathLike[str], None] = None,
        port: int = 0,
        use_stdio: Optional[bool] = None,
        log_level: LogLevel = "info",
        auto_start: bool = True,
        auto_restart: bool = True,
        github_token: Optional[str] = None,
        use_logged_in_user: Optional[bool] = None,
        env: Optional[dict[str, str]] = None,
    ):

python/test_client.py

…eArguments

SteveSandersonMS · 2026-02-20T18:35:49Z

python/copilot/client.py

+        github_token: Optional[str] = None,
+        use_logged_in_user: Optional[bool] = None,
+        env: Optional[dict[str, str]] = None,
+    ):


Managing all these overloads feels painful but if this is what you recommend as the most idiomatic Python solution then I'll gladly defer to you.

Do IDEs really not provide good hinting when passing an object literal in as an argument?

I don't quite follow what you mean by "good hinting when passing an object literal"? The overloads are there for type checkers because you have arguments that are valid only in certain situations (e.g. cli_args only applies when cli_path is provided).

SteveSandersonMS · 2026-02-20T18:37:03Z

python/copilot/client.py

+                Mutually exclusive with cli_path and use_stdio.
+            cwd: Working directory for the CLI process. Accepts strings
+                or path-like objects (default: current working directory).
+            port: Port for the CLI server in TCP mode (default: 0 for random).


Suggested change

port: Port for the CLI server in TCP mode (default: 0 for random).

port: Port for the CLI server in TCP mode (default: 0 for OS-assigned).

SteveSandersonMS

Looks good, though I think there are also a lot of samples to update under https://github.com/github/copilot-sdk/blob/main/test/scenarios

brettcannon and others added 5 commits February 19, 2026 10:47

refactor(python): convert CopilotClient.__init__ from dict to keyword…

72041de

… arguments Replace the options dict parameter with explicit keyword-only arguments for better IDE support, type checking, and discoverability. Update docstrings, examples, and all call sites accordingly.

feat(python): accept path-like objects in CopilotClient.__init__

63b2238

Update cli_path and cwd parameters to accept Union[str, os.PathLike[str], None]. Values are normalized to str via os.fspath() before storage.

docs(python): document env param and nullable types in README

709ec4e

Add env parameter to CopilotClient Options and update type annotations to show | None for all parameters that accept None. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

brettcannon requested a review from a team as a code owner February 19, 2026 22:54

Copilot AI review requested due to automatic review settings February 19, 2026 22:54

Copilot started reviewing on behalf of brettcannon February 19, 2026 22:55 View session

Merge remote-tracking branch 'upstream/main' into api-changes

0563506

# Conflicts: # python/copilot/client.py

Copilot AI reviewed Feb 19, 2026

View reviewed changes

python/test_client.py Show resolved Hide resolved

brettcannon added 6 commits February 19, 2026 15:02

Merge branch 'main' into api-changes

11785ee

refactor(tests): use os.fspath for Path-like arguments in TestPathLik…

eda3e4f

…eArguments

Fix a screw-up in a replay

537ed56

docs: add cli_args option to CopilotClient documentation

f90fe6a

feat(tests): add os import for path handling in test_client.py

b161dd6

Fix formatting

d247f27

SteveSandersonMS reviewed Feb 20, 2026

View reviewed changes

SteveSandersonMS approved these changes Feb 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Refactor CopilotClient initialization and enhance documentation#519

Refactor CopilotClient initialization and enhance documentation#519
brettcannon wants to merge 12 commits intogithub:mainfrom
brettcannon:api-changes

brettcannon commented Feb 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

SteveSandersonMS Feb 20, 2026 •

edited

Loading

Uh oh!

brettcannon Feb 20, 2026

Uh oh!

SteveSandersonMS Feb 20, 2026

Uh oh!

SteveSandersonMS left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	port: Port for the CLI server in TCP mode (default: 0 for random).
	port: Port for the CLI server in TCP mode (default: 0 for OS-assigned).

Comments

Conversation

brettcannon commented Feb 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

SteveSandersonMS Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brettcannon Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

SteveSandersonMS Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

SteveSandersonMS left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SteveSandersonMS Feb 20, 2026 •

edited

Loading